Skip to main content

Tips & Tricks

Use the Blotch Library​

Before redeveloping existing concepts, have a look at the Blotch Library to see if there is a component or hook which solves your problem. If the component or hook doesn't exist, and you think it should, please raise it as a suggestion in our Forum or Discord for it to be added.

tip

Visit the Blotch Library documentation to get started

Read their API docs​

Want to add data from your favorite thing into your Widget? Try explore the thing's developer documentation website. They should have a section describing their API (if they have one). Read and understand how to use it, and what end points they expose, and any authentication requirements. Once you are comfortable with their API, learn how to communicate with their API in Data Fetching.

Type Definitions​

TypeScript is a first class supported feature in the Widget Designer. It is best to leverage this as much as possible to:

  • Help you create less error-prone Widgets.
  • Add the guard rails when coding to prevent any guess work.
  • Help you understand your code quicker when coming back to it (for example to make an update).
  • Help others understand your code when they fork it.

Try to always create type definitions, especially when Data Fetching.

Easily create Type Definitions​

If you are retrieving data from a server, you may want to type the Response to enable auto-completion and type hints.

You can quickly create type definitions by using QuickType. Paste in a sample JSON response and types are automatically generated for you. Copy and paste this into the top (just below imports) of the Widget!

Bypass CORS​

CORS is a common problem everyone faces, so we have created a hook in our library to easily solve this. Read more in Data Fetching.

Always pin dependencies​

As mentioned in the Dependencies section, it is important to pin dependencies to avoid breaking changes upstream breaking your Widget.

Put secrets in .env​

Do not put API Keys or any secrets in the Widget code itself. This is because it is public and can be read other users.

Put secrets you want to store securely in the Secrets section in .env.

When a Widget is forked, the secrets won't be forked over.

Outer Padding​

The user installing your Widget has the ability to add padding themselves when they install the Widget onto their Blotch Smart Frame. Thus is it unnecessary and adds extraneous padding if you add your own outer padding at the Widget level.

There are obviously some exceptions and niche edge cases, so it's best to use your judgement.

Inputs​

Select​

When adding a Select based Input, it is recommended to use human readable text for the options. Then, on the Widget side, create a mapping between the human readable text and the code representation.

Example​

Imagine you create a Widget to show the latest results of football matches. The Widgets expose a Select of which the user can choose which league to get the data from. The API expects a 2 letter abbreviation of the league name.

  1. Create a Select Input with human readable options for the user to select. E.g. Champions League, Euros, World Cup. You can name this Input: league.

  2. Create a map in the code to map the human readable names to the 2 letter abbreviation:

    const leagueMap = {
      "Champions League": "CL",
      Euros: "EU",
      "World Cup": "WC",
    };

  3. The Widget will have a new Prop league of which you can use to get the 2 letter abbreviation from leagueMap

    const twoLetterAbbreviation = leagueMap[league];

  4. You can then use this for further data fetching or processing in the Widget.

warning

Of course you can create a Select Input with CL, EU, and WC as its options - But it is cryptic and not descriptive, and would cause fustration amongst users.